home *** CD-ROM | disk | FTP | other *** search
/ Language/OS - Multiplatform Resource Library / LANGUAGE OS.iso / russell / gc.lha / gc.h < prev    next >
C/C++ Source or Header  |  1993-02-24  |  12KB  |  284 lines
  1. /* 
  2.  * Copyright 1988, 1989 Hans-J. Boehm, Alan J. Demers
  3.  * Copyright (c) 1991 by Xerox Corporation.  All rights reserved.
  4.  *
  5.  * THIS MATERIAL IS PROVIDED AS IS, WITH ABSOLUTELY NO WARRANTY EXPRESSED
  6.  * OR IMPLIED.  ANY USE IS AT YOUR OWN RISK.
  7.  *
  8.  * Permission is hereby granted to copy this garbage collector for any purpose,
  9.  * provided the above notices are retained on all copies.
  10.  */
  11.  
  12. #ifndef GC_H
  13.  
  14. # define GC_H
  15.  
  16. # include <stddef.h>
  17.  
  18. /* Define word and signed_word to be unsigned and signed types of the     */
  19. /* size as char * or void *.  There seems to be no way to do this    */
  20. /* even semi-portably.  The following is probably no better/worse     */
  21. /* than almost anything else.                        */
  22. /* The ANSI standard suggests that size_t and ptr_diff_t might be     */
  23. /* better choices.  But those appear to have incorrect definitions    */
  24. /* on may systems.  Notably "typedef int size_t" seems to be both    */
  25. /* frequent and WRONG.                            */
  26. typedef unsigned long word;
  27. typedef long signed_word;
  28.  
  29. /* Public read-only variables */
  30.  
  31. extern word GC_heapsize;       /* Heap size in bytes */
  32.  
  33. extern word GC_gc_no;    /* Counter incremented per collection.      */
  34.             /* Includes empty GCs at startup.        */
  35.  
  36. /* Public R/W variables */
  37.  
  38. extern int GC_dont_gc;    /* Dont collect unless explicitly requested, e.g. */
  39.             /* beacuse it's not safe.              */
  40.  
  41. extern int GC_dont_expand;
  42.             /* Dont expand heap unless explicitly requested */
  43.             /* or forced to.                */
  44.             
  45. extern word GC_non_gc_bytes;
  46.             /* Bytes not considered candidates for collection. */
  47.             /* Used only to control scheduling of collections. */
  48.  
  49. extern word GC_free_space_divisor;
  50.             /* We try to make sure that we allocate at     */
  51.             /* least N/GC_free_space_divisor bytes between    */
  52.             /* collections, where N is the heap size plus    */
  53.             /* a rough estimate of the root set size.    */
  54.             /* Initially, GC_free_space_divisor = 4.    */
  55.             /* Increasing its value will use less space    */
  56.             /* but more collection time.  Decreasing it    */
  57.             /* will appreciably decrease collection time    */
  58.             /* at the expens of space.            */
  59.             /* GC_free_space_divisor = 1 will effectively    */
  60.             /* disable collections.                */
  61.             
  62. /* Public procedures */
  63. /*
  64.  * general purpose allocation routines, with roughly malloc calling conv.
  65.  * The atomic versions promise that no relevant pointers are contained
  66.  * in the object.  The nonatomic version guarantees that the new object
  67.  * is cleared.
  68.  */
  69. # ifdef __STDC__
  70.   extern void * GC_malloc(size_t size_in_bytes);
  71.   extern void * GC_malloc_atomic(size_t size_in_bytes);
  72. # else
  73.   extern char * GC_malloc(/* size_in_bytes */);
  74.   extern char * GC_malloc_atomic(/* size_in_bytes */);
  75. # endif
  76.  
  77. /* Explicitly deallocate an object.  Dangerous if used incorrectly.     */
  78. /* Requires a pointer to the base of an object.                */
  79. # ifdef __STDC__
  80.   extern void GC_free(void * object_addr);
  81. # else
  82.   extern void GC_free(/* object_addr */);
  83. # endif
  84.  
  85. /* Return a pointer to the base (lowest address) of an object given    */
  86. /* a pointer to a location within the object.                */
  87. /* Return 0 if displaced_pointer doesn't point to within a valid    */
  88. /* object.                                */
  89. # ifdef __STDC__
  90.   void * GC_base(void * displaced_pointer);
  91. # else
  92.   char * GC_base(/* char * displaced_pointer */);
  93. # endif
  94.  
  95. /* Given a pointer to the base of an object, return its size in bytes.    */
  96. /* The returned size may be slightly larger than what was originally    */
  97. /* requested.                                */
  98. # ifdef __STDC__
  99.   size_t GC_size(void * object_addr);
  100. # else
  101.   size_t GC_size(/* char * object_addr */);
  102. # endif
  103.  
  104. /* For compatibility with C library.  This is occasionally faster than    */
  105. /* a malloc followed by a bcopy.  But if you rely on that, either here    */
  106. /* or with the standard C library, your code is broken.  In my        */
  107. /* opinion, it shouldn't have been invented, but now we're stuck. -HB    */
  108. # ifdef __STDC__
  109.     extern void * GC_realloc(void * old_object, size_t new_size_in_bytes);
  110. # else
  111.     extern char * GC_realloc(/* old_object, new_size_in_bytes */);
  112. # endif
  113.  
  114.  
  115. /* Explicitly increase the heap size.    */
  116. /* Returns 0 on failure, 1 on success.  */
  117. extern int GC_expand_hp(/* number_of_4K_blocks */);
  118.  
  119. /* Clear the set of root segments */
  120. extern void GC_clear_roots();
  121.  
  122. /* Add a root segment */
  123. extern void GC_add_roots(/* low_address, high_address_plus_1 */);
  124.  
  125. /* Add a displacement to the set of those considered valid by the    */
  126. /* collector.  GC_register_displacement(n) means that if p was returned */
  127. /* by GC_malloc, then (char *)p + n will be considered to be a valid    */
  128. /* pointer to n.  N must be small and less than the size of p.        */
  129. /* (All pointers to the interior of objects from the stack are        */
  130. /* considered valid in any case.  This applies to heap objects and    */
  131. /* static data.)                            */
  132. /* Preferably, this should be called before any other GC procedures.    */
  133. /* Calling it later adds to the probability of excess memory        */
  134. /* retention.                                */
  135. void GC_register_displacement(/* n */);
  136.  
  137. /* Explicitly trigger a collection.     */
  138. void GC_gcollect();
  139.  
  140. /* Debugging (annotated) allocation.  GC_gcollect will check         */
  141. /* objects allocated in this way for overwrites, etc.            */
  142. # ifdef __STDC__
  143.   extern void * GC_debug_malloc(size_t size_in_bytes,
  144.                   char * descr_string, int descr_int);
  145.   extern void * GC_debug_malloc_atomic(size_t size_in_bytes,
  146.                          char * descr_string, int descr_int);
  147.   extern void GC_debug_free(void * object_addr);
  148.   extern void * GC_debug_realloc(void * old_object,
  149.                     size_t new_size_in_bytes,
  150.                     char * descr_string, int descr_int);
  151. # else
  152.   extern char * GC_debug_malloc(/* size_in_bytes, descr_string, descr_int */);
  153.   extern char * GC_debug_malloc_atomic(/* size_in_bytes, descr_string,
  154.                         descr_int */);
  155.   extern void GC_debug_free(/* object_addr */);
  156.   extern char * GC_debug_realloc(/* old_object, new_size_in_bytes,
  157.                           descr_string, descr_int */);
  158. # endif
  159. # ifdef GC_DEBUG
  160. #   define GC_MALLOC(sz) GC_debug_malloc(sz, __FILE__, __LINE__)
  161. #   define GC_MALLOC_ATOMIC(sz) GC_debug_malloc_atomic(sz, __FILE__, __LINE__)
  162. #   define GC_REALLOC(old, sz) GC_debug_realloc(old, sz, __FILE__, \
  163.                                    __LINE__)
  164. #   define GC_FREE(p) GC_debug_free(p)
  165. #   define GC_REGISTER_FINALIZER(p, f, d, of, od) \
  166.     GC_register_finalizer(GC_base(p), GC_debug_invoke_finalizer, \
  167.                   GC_make_closure(f,d), of, od)
  168. # else
  169. #   define GC_MALLOC(sz) GC_malloc(sz)
  170. #   define GC_MALLOC_ATOMIC(sz) GC_malloc_atomic(sz)
  171. #   define GC_REALLOC(old, sz) GC_realloc(old, sz)
  172. #   define GC_FREE(p) GC_free(p)
  173. #   define GC_REGISTER_FINALIZER(p, f, d, of, od) \
  174.     GC_register_finalizer(p, f, d, of, od)
  175. # endif
  176.  
  177. /* Finalization.  Some of these primitives are grossly unsafe.        */
  178. /* The idea is to make them both cheap, and sufficient to build        */
  179. /* a safer layer, closer to PCedar finalization.            */
  180. /* The interface represents my conclusions from a long discussion    */
  181. /* with Alan Demers, Dan Greene, Carl Hauser, Barry Hayes,         */
  182. /* Christian Jacobi, and Russ Atkinson.  It's not perfect, and        */
  183. /* probably nobody else agrees with it.        Hans-J. Boehm  3/13/92    */
  184. # ifdef __STDC__
  185.   typedef void (*GC_finalization_proc)(void * obj, void * client_data);
  186. # else
  187.   typedef void (*GC_finalization_proc)(/* void * obj, void * client_data */);
  188. # endif
  189.     
  190. void GC_register_finalizer(/* void * obj,
  191.                   GC_finalization_proc fn, void * cd,
  192.                   GC_finalization_proc *ofn, void ** ocd */);
  193.     /* When obj is no longer accessible, invoke        */
  194.     /* (*fn)(obj, cd).  If a and b are inaccessible, and    */
  195.     /* a points to b (after disappearing links have been    */
  196.     /* made to disappear), then only a will be        */
  197.     /* finalized.  (If this does not create any new        */
  198.     /* pointers to b, then b will be finalized after the    */
  199.     /* next collection.)  Any finalizable object that    */
  200.     /* is reachable from itself by following one or more    */
  201.     /* pointers will not be finalized (or collected).    */
  202.     /* Thus cycles involving finalizable objects should    */
  203.     /* be avoided, or broken by disappearing links.        */
  204.     /* fn is invoked with the allocation lock held.  It may */
  205.     /* not allocate.  (Any storage it might need        */
  206.     /* should be preallocated and passed as part of cd.)     */
  207.     /* fn should terminate as quickly as possible, and    */
  208.     /* defer extended computation.                */
  209.     /* All but the last finalizer registered for an object  */
  210.     /* is ignored.                        */
  211.     /* Finalization may be removed by passing 0 as fn.    */
  212.     /* The old finalizer and client data are stored in    */
  213.     /* *ofn and *ocd.                    */ 
  214.     /* Fn is never invoked on an accessible object,        */
  215.     /* provided hidden pointers are converted to real     */
  216.     /* pointers only if the allocation lock is held, and    */
  217.     /* such conversions are not performed by finalization    */
  218.     /* routines.                        */
  219.  
  220. /* The following routine may be used to break cycles between    */
  221. /* finalizable objects, thus causing cyclic finalizable        */
  222. /* objects to be finalized in the cirrect order.  Standard    */
  223. /* use involves calling GC_register_disappearing_link(&p),    */
  224. /* where p is a pointer that is not followed by finalization    */
  225. /* code, and should not be considered in determining         */
  226. /* finalization order.                        */ 
  227. int GC_register_disappearing_link(/* void ** link */);
  228.     /* Link should point to a field of a heap allocated     */
  229.     /* object obj.  *link will be cleared when obj is    */
  230.     /* found to be inaccessible.  This happens BEFORE any    */
  231.     /* finalization code is invoked, and BEFORE any        */
  232.     /* decisions about finalization order are made.        */
  233.     /* This is useful in telling the finalizer that     */
  234.     /* some pointers are not essential for proper        */
  235.     /* finalization.  This may avoid finalization cycles.    */
  236.     /* Note that obj may be resurrected by another        */
  237.     /* finalizer, and thus the clearing of *link may    */
  238.     /* be visible to non-finalization code.          */
  239.     /* There's an argument that an arbitrary action should  */
  240.     /* be allowed here, instead of just clearing a pointer. */
  241.     /* But this causes problems if that action alters, or     */
  242.     /* examines connectivity.                */
  243.     /* Returns 1 if link was already registered, 0        */
  244.     /* otherise.                        */
  245. int GC_unregister_disappearing_link(/* void ** link */);
  246.     /* Returns 0 if link was not actually registered.    */
  247.  
  248. /* Auxiliary fns to make finalization work correctly with displaced    */
  249. /* pointers introduced by the debugging allocators.            */
  250. # ifdef __STDC__
  251.     void * GC_make_closure(GC_finalization_proc fn, void * data);
  252.     void GC_debug_invoke_finalizer(void * obj, void * data);
  253. # else
  254.     char * GC_make_closure(/* GC_finalization_proc fn, char * data */);
  255.     void GC_debug_invoke_finalizer(/* void * obj, void * data */);
  256. # endif
  257.  
  258.     
  259. /* The following is intended to be used by a higher level    */
  260. /* (e.g. cedar-like) finalization facility.  It is expected    */
  261. /* that finalization code will arrange for hidden pointers to    */
  262. /* disappear.  Otherwise objects can be accessed after they    */
  263. /* have been collected.                        */
  264. # ifdef I_HIDE_POINTERS
  265. #   ifdef __STDC__
  266. #     define HIDE_POINTER(p) (~(size_t)(p))
  267. #     define REVEAL_POINTER(p) ((void *)(HIDE_POINTER(p)))
  268. #   else
  269. #     define HIDE_POINTER(p) (~(unsigned long)(p))
  270. #     define REVEAL_POINTER(p) ((char *)(HIDE_POINTER(p)))
  271. #   endif
  272.     /* Converting a hidden pointer to a real pointer requires verifying    */
  273.     /* that the object still exists.  This involves acquiring the      */
  274.     /* allocator lock to avoid a race with the collector.        */
  275.     typedef char * (*GC_fn_type)();
  276. #   ifdef __STDC__
  277.         void * GC_call_with_alloc_lock(GC_fn_type fn, void * client_data);
  278. #   else
  279.         char * GC_call_with_alloc_lock(/* GC_fn_type fn, char * client_data */);
  280. #   endif
  281. # endif
  282.  
  283. #endif
  284.